Summary

Adds async streaming helpers for long-poll monitoring of alerts and incidents. The SDK now exposes stream_alerts() and stream_incident_updates() as async iterators, enabling event-driven integrations without explicit polling loops.

Also includes OpenTelemetry auto-instrumentation for REST and MCP calls, providing observability into SDK operations.

What changed

Why this shape

Streaming

The mixin pattern lets async client inherit streaming capabilities alongside core REST operations. Poll-based iteration (vs SSE) is compatible with both the current long-poll endpoint and future SSE, keeping the public API unchanged when Hyperping's backend evolves. Default 30s poll interval is approximately 0.67% of the 300 req/min account limit, making continuous monitoring practical for event-driven workflows.

Alert and AlertType are derived from the monitors endpoint's down: bool and optional alert_type field, providing a minimal event model. The provisional AlertType.DEGRADED is unreachable until Hyperping ships a degraded state on the monitors endpoint.

OTel instrumentation

Spans are placed at the _request() / call_tool() level (one logical operation, wrapping the full retry loop) rather than per-attempt, matching HTTP semantic conventions. Using self._tracer (set at construction from get_tracer()) lets tests inject a local TracerProvider and lets power users override the tracer at runtime. The opentelemetry-api runtime dependency is lightweight; the SDK (exporters, processors) is the user's responsibility, keeping runtime footprint minimal.

Verification matrix

Acceptance criteria

• async def stream_alerts(self) -> AsyncIterator[Alert] added to AsyncHyperpingClient
• async def stream_incident_updates(uuid) -> AsyncIterator[IncidentUpdate] added to AsyncHyperpingClient
• Both use httpx2 stream context for efficient long-polling
• Alert and AlertType models exported from public API
• Default poll_interval 30s; configurable via parameter
• Streaming tests cover happy path, custom intervals, empty monitors, and error handling
• hyperping[otel] optional extra pulls opentelemetry-api>=1.20
• Every REST call emits span with http.request.method, url.full, server.address, hyperping.sdk.version
• Every MCP call emits span with rpc.method, rpc.system, server.address, hyperping.sdk.version
• Zero overhead when OTel not configured
• Test suite passes at >=85% coverage

Followups not in this PR

1. Duplicate poll_interval test (test_streaming.py:254-291): test_stream_alerts_respects_poll_interval and test_stream_alerts_custom_poll_interval verify the same property with different values. Remove one in a test cleanup pass.

2. AlertType.DEGRADED is unreachable from current stream_alerts implementation (which only produces DOWN/UP from monitor.down: bool). When Hyperping ships a degraded state in the monitors endpoint, wire it up and add a test.

3. Transient API error behavior undocumented: if _request raises (network timeout, 5xx) during a poll cycle, the exception propagates out of the generator and terminates it. Consider adding error-handling guidance to the docstring or a max_errors parameter in a future pass.

4. Empty-monitors edge case untested: stream_alerts with an empty monitors list correctly yields nothing and sets an empty baseline, but this path has no test. Add in the next test-coverage pass.

5. Untracked TypedDict test files: tests/unit/test_typeddict_input.py and tests/unit/test_async_typeddict_input.py reference a non-existent coerce_input symbol and break full-suite collection. Must be resolved (commit or delete) before the next feature branch adds tests.

6. Response status code as span attribute: requires enriching _execute_single_attempt to expose the raw response; deferred to a follow-up.

7. README/docs update for streaming and OTel usage patterns (out of scope for this ticket).

8. CHANGELOG entry (done at merge time per repo convention).